Remove the monolithic specification - #166

Summary

• Delete SPECS.md without replacing it with another specification or generated command reference.
• Remove every tracked reference and make the generated fleet-home workflow self-contained.
• Reduce the 27 provisional ADRs from PR docs: separate specification contracts from rationale #162 to 14 focused architectural records by deleting 11, merging two pairs, and tightening every retained record.
• Move the only missing operator guidance, the optional config/ keys, into README.md.

SPECS.md disposition

Repository and architecture

• What this file is: deleted as migration narration.
• Core principles: concise contributor routing now lives in AGENTS.md and CONTRIBUTING.md; the durable one-binary rationale remains in secondhand-rebuilds-firstmate-as-one-go-binary.md.
• Architecture overview: deleted because README.md and the package boundaries already represent it.
• Machine state and the prose corpus, Which to believe when they disagree, and Not Postgres, and no daemon: implementation and recovery behavior remain in internal/store, internal/state, their tests, and README.md; durable report-file authority was merged into the-report-channel-is-the-only-outcome-signal.md, and the short-lived-process consequence remains in the one-binary ADR.
• Directory layout: init, home, store, and config code and tests own the layout. README.md now lists the optional operator configuration keys that otherwise lacked a discoverable owner.
• Ambient context and First-run configuration: README.md, internal/sessionhook, internal/agentsmd, command help, and their focused tests own behavior. The hook-versus-rendered-file boundary remains in a tightened ADR.
• Output shape: internal/axi, command tests, root error tests, and generated AGENTS.md own behavior. The TOON default and JSON compatibility choice remains in a tightened ADR.

Commands

Every command contract is already represented by Cobra help, its implementation, and focused command or end-to-end tests, so the duplicate prose and exhaustive output examples were deleted:

• hand: cmd/root.go and root tests.
• hand init: cmd/init.go, README.md, init tests, and init e2e tests.
• hand config: cmd/config.go, generated AGENTS.md, and config tests.
• hand project add, list, upstream, remove, and sync: cmd/project.go, project package code, and project, PR, sync, and upstream tests.
• hand spawn: cmd/spawn.go, cmd/launch.go, internal/harness, and spawn and launch tests.
• hand status: cmd/status.go, cmd/statusview.go, and status tests.
• hand send: cmd/send.go and send unit and e2e tests.
• hand hold set and clear: cmd/hold.go, store and state hold code, and hold and status tests.
• hand deliver: cmd/deliver.go and deliver and upstream teardown tests.
• hand teardown and Completion store: cmd/teardown.go, internal/completion, and their focused tests. The fail-closed work guard and append-only completion storage choices remain as tightened ADRs.
• hand merge: cmd/merge.go, internal/ghutil, and merge tests.
• hand pr: cmd/pr.go, internal/project/pr.go, and PR detection tests.
• hand watch, One watcher per fleet home, Delivering an event, Notifying, Resuming a usage-limited worker, What survives a restart, and Pane-anchored facts across promote: cmd/watch.go, internal/watcher, internal/harness, cmd/promote.go, generated AGENTS.md, and focused unit and e2e tests. The singleton flock, exit-as-delivery, and harness-capability boundaries remain as tightened ADRs; exhaustive field and filter membership prose was deleted.
• hand promote: cmd/promote.go and promote and watcher cache tests.
• hand notify: cmd/notify.go, internal/notify, and tests.
• hand search and Optional qmd: cmd/search.go, internal/store/index.go, tests, and README.md.
• hand doctor: cmd/doctor.go, internal/agentsmd, AGENTS.md, and tests.

Integrations and formats

• Harness launch templates and its Claude Code, Codex, Grok, Pi, and OpenCode subsections: exact commands and capabilities live in internal/harness and its tests; launch confirmation lives in cmd/launch.go and tests. The interactive residency and split liveness/dialog boundary is one merged ADR.
• Herdr integration detail, Connection, Workspace and tab model, Agent state, Operations, and Herdr CLI calls: internal/herdr, command tests, internal/faketool/FIDELITY.md, and tests/contract own syntax and observed behavior. The report channel ADR retains only why herdr state cannot be task outcome.
• No-mistakes integration, Gate preflight, and Gate-run visibility: user workflow remains in README.md and command help; internal/project/gaterun.go and gate tests own behavior. The public-output-versus-private-database boundary remains in a tightened ADR.
• Brief format and Declared model and effort: internal/brief, generated AGENTS.md, tier resolution, and focused tests own the format and precedence.
• Backlog format: generated AGENTS.md and README.md own concise agent guidance. The stale example and unused implementation claims were deleted.
• Project registry format: internal/project, internal/store, parser and projection tests, and README.md own the format and user concept.

State, errors, tests, and release

• State management and Rules: internal/store, internal/state, internal/watcher, and their tests own behavior; only qualifying data-boundary rationale remains in ADRs.
• Report channel and Unacknowledged terminal reports: internal/state/report.go, watcher and status tests, and generated AGENTS.md own the contract; the outcome and plain-file authority rationale is one merged ADR.
• Holds: store, state, command, and status tests own behavior; the independent-row boundary remains in a tightened ADR.
• Concurrency: sqlite and named-lock implementations and tests own it.
• Collision guard: internal/worktree, spawn and collision tests, and FIDELITY.md own it.
• Recovery: README.md and generated AGENTS.md own operator guidance; the report ADR keeps why plain-file recovery exists.
• Migration: internal/store/migrate.go and migration tests own it.
• Schema versioning: internal/store/schemaversion.go and tests own the protocol; the PRAGMA boundary remains in a tightened ADR.
• Error handling, Philosophy, Exit codes, and Error output: cmd/root.go, cmd/precondition.go, internal/axi, generated AGENTS.md, and root, send, watch, and e2e tests own behavior.
• Testing strategy, Unit tests, and Integration tests: AGENTS.md, CONTRIBUTING.md, package documentation, FIDELITY.md, the shared fake, and the suites own the strategy. The stateful-fake boundary remains in a tightened ADR.
• Distribution, Install methods, Fleet home creation, Self-update, Release pipeline, and Repo scaffolding: README.md, CONTRIBUTING.md, command help, the Makefile, release configuration, tracked workflows, and their tests own these workflows. Duplicate narration and tracked-file inventories were deleted.

ADR disposition

Keep and tighten

• ambient-context-is-a-session-hook-not-a-file.md
• gate-checks-read-no-mistakes-output-not-its-database.md
• holds-are-their-own-table.md
• one-stateful-fake-per-external-tool.md
• one-watcher-per-fleet-home-guarded-by-an-flock.md
• output-is-toon-by-default-and-json-is-retained.md
• secondhand-rebuilds-firstmate-as-one-go-binary.md
• the-completion-store-is-an-uncapped-append-only-sibling.md
• the-landed-work-guard-reads-the-work-not-the-record.md
• the-schema-version-lives-in-pragma-user-version.md
• the-until-event-exit-is-the-delivery.md
• usage-limit-detection-is-a-harness-capability.md

Merge

• believe-the-status-file-and-ship-no-hand-dump.md merged into the-report-channel-is-the-only-outcome-signal.md; the destination now records both worker-outcome ownership and plain-file authority.
• launch-confirmation-trusts-herdr-not-the-screen.md merged into harness-templates-launch-interactively.md; the destination now records both interactive residency and the split between herdr liveness and dialog text.

Delete because executable owners already hold the fact

• a-fork-projects-upstream-is-declared-never-inferred.md
• a-silent-report-channel-is-parked-on-three-bounds.md
• a-steer-that-never-lands-leaves-a-durable-trace.md
• an-unrecorded-pr-is-recovered-by-head-ref.md
• deliver-names-the-state-instead-of-widening-force.md
• herdr-workspace-labels-carry-a-hand-prefix.md
• notify-is-a-filtered-consumer-of-the-event-stream.md
• the-collision-guard-keys-on-the-lease-id.md
• the-report-offset-is-trusted-only-with-a-digest.md
• the-watcher-persists-what-it-announces.md

Relocate contributor policy

• the-comment-rule-is-two-mechanical-checks.md: CONTRIBUTING.md and tools/commentlint already own the rule, exemptions, and enforcement, so the ADR was deleted.

Final retained collection: 14 ADRs plus docs/adr/README.md.

Verification

• make lint
• go build ./...
• go test -race ./...
• make e2e
• make contract
• Focused generated-output regression test observed failing before the template change and passing after it.
• A fresh fleet home created by the built final binary has no removed-document reference in generated AGENTS.md or bare session-start output.
• Tracked source scan, retained-link scan, diff check, comment scan, forbidden-character scan, and final ADR count completed.

Closes #163